/*
	File:    	SimpleQueue.h
	Package: 	Apple CarPlay Communication Plug-in.
	Abstract: 	n/a 
	Version: 	450.14
	
	Disclaimer: IMPORTANT: This Apple software is supplied to you, by Apple Inc. ("Apple"), in your
	capacity as a current, and in good standing, Licensee in the MFi Licensing Program. Use of this
	Apple software is governed by and subject to the terms and conditions of your MFi License,
	including, but not limited to, the restrictions specified in the provision entitled ”Public 
	Software”, and is further subject to your agreement to the following additional terms, and your 
	agreement that the use, installation, modification or redistribution of this Apple software
	constitutes acceptance of these additional terms. If you do not agree with these additional terms,
	please do not use, install, modify or redistribute this Apple software.
	
	Subject to all of these terms and in consideration of your agreement to abide by them, Apple grants
	you, for as long as you are a current and in good-standing MFi Licensee, a personal, non-exclusive 
	license, under Apple's copyrights in this original Apple software (the "Apple Software"), to use, 
	reproduce, and modify the Apple Software in source form, and to use, reproduce, modify, and 
	redistribute the Apple Software, with or without modifications, in binary form. While you may not 
	redistribute the Apple Software in source form, should you redistribute the Apple Software in binary
	form, you must retain this notice and the following text and disclaimers in all such redistributions
	of the Apple Software. Neither the name, trademarks, service marks, or logos of Apple Inc. may be
	used to endorse or promote products derived from the Apple Software without specific prior written
	permission from Apple. Except as expressly stated in this notice, no other rights or licenses, 
	express or implied, are granted by Apple herein, including but not limited to any patent rights that
	may be infringed by your derivative works or by other works in which the Apple Software may be 
	incorporated.  
	
	Unless you explicitly state otherwise, if you provide any ideas, suggestions, recommendations, bug 
	fixes or enhancements to Apple in connection with this software (“Feedback”), you hereby grant to
	Apple a non-exclusive, fully paid-up, perpetual, irrevocable, worldwide license to make, use, 
	reproduce, incorporate, modify, display, perform, sell, make or have made derivative works of,
	distribute (directly or indirectly) and sublicense, such Feedback in connection with Apple products 
	and services. Providing this Feedback is voluntary, but if you do provide Feedback to Apple, you 
	acknowledge and agree that Apple may exercise the license granted above without the payment of 
	royalties or further consideration to Participant.
	
	The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO WARRANTIES, EXPRESS OR 
	IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY 
	AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR
	IN COMBINATION WITH YOUR PRODUCTS.
	
	IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES 
	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	PROFITS; OR BUSINESS INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION 
	AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
	(INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE 
	POSSIBILITY OF SUCH DAMAGE.
	
	Copyright (C) 2017 Apple Inc. All Rights Reserved. Not to be used or disclosed without permission from Apple.
*/

#ifndef SIMPLEQUEUE_H
#define SIMPLEQUEUE_H

#include "CommonServices.h"
#include CF_HEADER
#include CF_RUNTIME_HEADER

/*!
	@header
	@abstract	API for creating and using SimpleQueues.
	@discussion	SimpleQueues are CF-based objects that implement a simple lockless FIFO queue of (void *)
				elements. The elements are not assumed to be pointers; they could be simple pointer-sized
				numeric values (although NULL or 0-valued elements are not allowed). If the elements are
				in fact pointers to allocated memory buffers, buffer lifetime management must be handled
				externally.
				
				A SimpleQueue can safely handle one enqueueing thread and one dequeueing thread.
				
				SimpleQueues are lockless. As such, Enqueues and/or Dequeues can occur on the CoreAudio ioProc
				thread, where locking/blocking is forbidden.
				
				The current status of a SimpleQueue can be interrogated.  Clients can get the current number
				of elements in the queue (GetCount) as well as the maximum capacity of the queue (GetCapacity).
				There is also a convenience macro (GetFullness) that uses those two APIs to compute a Float32
				between 0.0 and 1.0, representing the fullness of the queue.  For example, 0.0 represents an
				empty queue, 0.5 represents a queue that is half-full, and 1.0 represents a full queue.
				
				SimpleQueues can be reset. This returns them to a newly created state, with no elements in the queue
				(but with the maximum capacity unchanged).
*/

#ifdef __cplusplus
extern "C" {
#endif
    
#pragma pack(push, 4)

//=============================================================================
//	Errors
//=============================================================================

/*!
	@enum SimpleQueue Errors
	@discussion The OSStatus errors returned from the SimpleQueue APIs.
	@constant	kSimpleQueueError_AllocationFailed			An allocation failed.
	@constant	kSimpleQueueError_RequiredParameterMissing	NULL or 0 was passed for a required parameter.
	@constant	kSimpleQueueError_ParameterOutOfRange			An out-of-range value was passed for a parameter with a restricted valid range.
	@constant	kSimpleQueueError_QueueIsFull					Operation failed because queue was full.
*/

enum
{
	kSimpleQueueError_AllocationFailed					= -12770,
	kSimpleQueueError_RequiredParameterMissing			= -12771,
	kSimpleQueueError_ParameterOutOfRange					= -12772,
	kSimpleQueueError_QueueIsFull							= -12773,
};

//=============================================================================
//	Types
//=============================================================================

/*!
	@typedef	SimpleQueueRef
	@abstract	A reference to a SimpleQueue, a CF object that implements a simple lockless queue of (void *) elements.
		
*/
typedef struct opaqueSimpleQueue *SimpleQueueRef;

//=============================================================================

/*!
	@function	SimpleQueueGetTypeID
	@abstract	Returns the CFTypeID of SimpleQueue objects.
	@discussion	You can check if a CFTypeRef object is actually a SimpleQueue by comparing CFGetTypeID(object)
				with SimpleQueueGetTypeID().
	@result		CFTypeID of SimpleQueue objects.
*/

CFTypeID SimpleQueueGetTypeID(void);

/*!
	@function	SimpleQueueCreate
    @abstract	Creates a SimpleQueue.
    @discussion On return, the caller owns the returned SimpleQueue, and must release it when done with it.
    @result		Returns noErr if the call succeeds.  Returns kSimpleQueueError_ParameterOutOfRange if
				capacity is negative.
*/

OSStatus SimpleQueueCreate(
	CFAllocatorRef allocator,					/*! @param allocator
																Allocator used to allocate storage for the queue. */
	int32_t capacity,										/*! @param capacity
																Capacity of the queue (maximum number of elements holdable at any
																given time).  Required (must not be 0).  Must be a positive value. */
	SimpleQueueRef * queueOut);		/*! @param queueOut Returned newly created queue is written to this address. */


/*!
	@function	SimpleQueueEnqueue
    @abstract	Enqueues an element on the queue.
    @discussion	If the queue is full, this operation will fail.
	@result		Returns noErr if the call succeeds, kSimpleQueueError_QueueIsFull if the queue is full.
*/

OSStatus SimpleQueueEnqueue(
	SimpleQueueRef queue,		/*! @param queue
												The queue on which to enqueue the element. Must not be NULL. */
	const void * element);		/*! @param element
												Element to enqueue. Must not be NULL (NULL is returned from Dequeue
												to indicate an empty queue). */

/*!
	@function	SimpleQueueDequeue
    @abstract	Dequeues an element from the queue.
    @discussion If the queue is empty, NULL will be returned.
	@result		The dequeued element.  NULL if the queue was empty, or if there was some other error.
*/

const void * SimpleQueueDequeue(
	SimpleQueueRef queue); 	/*! @param queue
											The queue from which to dequeue an element. Must not be NULL. */


/*!
	@function	SimpleQueueGetHead
    @abstract	Returns the element at the head of the queue.
    @discussion If the queue is empty, NULL will be returned.
	@result		The head element.  NULL if the queue was empty, or if there was some other error.
*/

const void * SimpleQueueGetHead(
	SimpleQueueRef queue); 	/*! @param queue
											The queue from which to get the head element. Must not be NULL. */


/*!
	@function	SimpleQueueReset
    @abstract	Resets the queue.
    @discussion	This function resets the queue to its empty state;  all values
				in the queue prior to reset are lost.   Note that SimpleQueueReset
				is not synchronized in any way, so the reader thread and writer thread
				must be held off by the client during this operation.
	@result		Returns noErr if the call succeeds.
*/

OSStatus SimpleQueueReset(
	SimpleQueueRef queue); 	/*! @param queue
											The queue to reset. Must not be NULL. */


/*!
	@function	SimpleQueueGetCapacity
    @abstract	Returns the number of elements that can be held in the queue.
	@result		The number of elements that can be held in the queue.  Returns
				0 if there is an error.
*/

int32_t SimpleQueueGetCapacity(
	SimpleQueueRef queue); 	/*! @param queue
											The queue being interrogated. Must not be NULL. */


/*!
	@function	SimpleQueueGetCount
    @abstract	Returns the number of elements currently on the queue.
	@result		The number of elements currently in the queue. Returns 0 if there is an error.
*/

int32_t SimpleQueueGetCount(
	SimpleQueueRef queue); 	/*! @param queue
											The queue being interrogated. Must not be NULL. */

/*!
	@define		SimpleQueueGetFullness
	A convenience macro that returns GetCount/GetCapacity, computed in floating point.  0.0 is empty, 0.5 is half full, 1.0 is full.
	Returns 0.0 if there is an error (eg. if queue is NULL).
*/
#define SimpleQueueGetFullness(queue) ( SimpleQueueGetCapacity(queue) ? \
											( ((Float32)SimpleQueueGetCount(queue)) / ((Float32)SimpleQueueGetCapacity(queue)) ) \
											: 0.0f )

#pragma pack(pop)
    
#if defined(__cplusplus)
}
#endif

#endif // ! SIMPLEQUEUE_H
